

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Tutorial &mdash; Mod_python v3.5.0-3.5.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '3.5.0-3.5.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/sidebar.js"></script>
    <link rel="author" title="About these documents" href="about.html" />
    <link rel="copyright" title="Copyright" href="copyright.html" />
    <link rel="top" title="Mod_python v3.5.0-3.5.0 documentation" href="index.html" />
    <link rel="next" title="Python API" href="pythonapi.html" />
    <link rel="prev" title="Installation" href="installation.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="pythonapi.html" title="Python API"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="installation.html" title="Installation"
             accesskey="P">previous</a> |</li>
        <li><a href="contents.html">Mod_python v3.5.0-3.5.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="tutorial">
<span id="id1"></span><h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h1>
<p><em>So how can I make this work?</em></p>
<p>This is a quick guide to getting started with mod_python programming
once you have it installed. This is not an installation manual.</p>
<p>It is also highly recommended to read (at least the top part of)
the section <a class="reference internal" href="pythonapi.html#pythonapi"><em>Python API</em></a> after completing this tutorial.</p>
<div class="section" id="a-quick-start-with-the-publisher-handler">
<span id="tut-pub"></span><h2>A Quick Start with the Publisher Handler<a class="headerlink" href="#a-quick-start-with-the-publisher-handler" title="Permalink to this headline">¶</a></h2>
<p>This section provides a quick overview of the Publisher handler for
those who would like to get started without getting into too much
detail. A more thorough explanation of how mod_python handlers work
and what a handler actually is follows on in the later sections of the
tutorial.</p>
<p>The <a class="reference internal" href="handlers.html#hand-pub"><em>Publisher Handler</em></a> is provided as one of the standard
mod_python handlers. To get the publisher handler working, you will
need the following lines in your config:</p>
<div class="highlight-python"><pre>AddHandler mod_python .py
PythonHandler mod_python.publisher
PythonDebug On</pre>
</div>
<p>The following example demonstrates a simple feedback form. The form
asks for a name, e-mail address and a comment which are then used to
construct and send a message to the webmaster.  This simple
application consists of two files: <tt class="file docutils literal"><span class="pre">form.html</span></tt> - the form to
collect the data, and <tt class="file docutils literal"><span class="pre">form.py</span></tt> - the target of the form&#8217;s
action.</p>
<p>Here is the html for the form:</p>
<div class="highlight-python"><pre>&lt;html&gt;
   Please provide feedback below:
&lt;p&gt;
&lt;form action="form.py/email" method="POST"&gt;

   Name:    &lt;input type="text" name="name"&gt;&lt;br&gt;
   Email:   &lt;input type="text" name="email"&gt;&lt;br&gt;
   Comment: &lt;textarea name="comment" rows=4 cols=20&gt;&lt;/textarea&gt;&lt;br&gt;
   &lt;input type="submit"&gt;

&lt;/form&gt;
&lt;/html&gt;</pre>
</div>
<p>The <tt class="docutils literal"><span class="pre">action</span></tt> element of the <tt class="docutils literal"><span class="pre">&lt;form&gt;</span></tt> tag points to
<tt class="docutils literal"><span class="pre">form.py/email</span></tt>. We are going to create a file called
<tt class="file docutils literal"><span class="pre">form.py</span></tt>, like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">smtplib</span>

<span class="n">WEBMASTER</span> <span class="o">=</span> <span class="s">&quot;webmaster&quot;</span>   <span class="c"># webmaster e-mail</span>
<span class="n">SMTP_SERVER</span> <span class="o">=</span> <span class="s">&quot;localhost&quot;</span> <span class="c"># your SMTP server</span>

<span class="k">def</span> <span class="nf">email</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">email</span><span class="p">,</span> <span class="n">comment</span><span class="p">):</span>

    <span class="c"># make sure the user provided all the parameters</span>
    <span class="k">if</span> <span class="ow">not</span> <span class="p">(</span><span class="n">name</span> <span class="ow">and</span> <span class="n">email</span> <span class="ow">and</span> <span class="n">comment</span><span class="p">):</span>
        <span class="k">return</span> <span class="s">&quot;A required parameter is missing, </span><span class="se">\</span>
<span class="s">               please go back and correct the error&quot;</span>

    <span class="c"># create the message text</span>
    <span class="n">msg</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span><span class="se">\</span>
<span class="s">From: </span><span class="si">%s</span><span class="s"></span>
<span class="s">Subject: feedback</span>
<span class="s">To: </span><span class="si">%s</span><span class="s"></span>

<span class="s">I have the following comment:</span>

<span class="si">%s</span><span class="s"></span>

<span class="s">Thank You,</span>

<span class="si">%s</span><span class="s"></span>

<span class="s">&quot;&quot;&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">email</span><span class="p">,</span> <span class="n">WEBMASTER</span><span class="p">,</span> <span class="n">comment</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>

    <span class="c"># send it out</span>
    <span class="n">conn</span> <span class="o">=</span> <span class="n">smtplib</span><span class="o">.</span><span class="n">SMTP</span><span class="p">(</span><span class="n">SMTP_SERVER</span><span class="p">)</span>
    <span class="n">conn</span><span class="o">.</span><span class="n">sendmail</span><span class="p">(</span><span class="n">email</span><span class="p">,</span> <span class="p">[</span><span class="n">WEBMASTER</span><span class="p">],</span> <span class="n">msg</span><span class="p">)</span>
    <span class="n">conn</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>

    <span class="c"># provide feedback to the user</span>
    <span class="n">s</span> <span class="o">=</span> <span class="s">&quot;&quot;&quot;</span><span class="se">\</span>
<span class="s">&lt;html&gt;</span>

<span class="s">Dear </span><span class="si">%s</span><span class="s">,&lt;br&gt;</span>
<span class="s">Thank You for your kind comments, we</span>
<span class="s">will get back to you shortly.</span>

<span class="s">&lt;/html&gt;&quot;&quot;&quot;</span> <span class="o">%</span> <span class="n">name</span>

    <span class="k">return</span> <span class="n">s</span>
</pre></div>
</div>
<p>When the user clicks the Submit button, the publisher handler will
load the <tt class="xref py py-func docutils literal"><span class="pre">email()</span></tt> function in the <tt class="xref py py-mod docutils literal"><span class="pre">form</span></tt> module,
passing it the form fields as keyword arguments. It will also pass the
request object as <tt class="docutils literal"><span class="pre">req</span></tt>.</p>
<p>You do not have to have <tt class="docutils literal"><span class="pre">req</span></tt> as one of the arguments if you do not
need it. The publisher handler is smart enough to pass your function
only those arguments that it will accept.</p>
<p>The data is sent back to the browser via the return value of the
function.</p>
<p>Even though the Publisher handler simplifies mod_python programming a
great deal, all the power of mod_python is still available to this
program, since it has access to the request object. You can do all the
same things you can do with a &#8220;native&#8221; mod_python handler, e.g. set
custom headers via <tt class="docutils literal"><span class="pre">req.headers_out</span></tt>, return errors by raising
<tt class="xref py py-exc docutils literal"><span class="pre">apache.SERVER_ERROR</span></tt> exceptions, write or read directly to
and from the client via <tt class="xref py py-meth docutils literal"><span class="pre">req.write()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">req.read()</span></tt>,
etc.</p>
<p>Read Section <a class="reference internal" href="handlers.html#hand-pub"><em>Publisher Handler</em></a> for more information on the publisher
handler.</p>
</div>
<div class="section" id="quick-overview-of-how-apache-handles-requests">
<span id="tut-overview"></span><h2>Quick Overview of how Apache Handles Requests<a class="headerlink" href="#quick-overview-of-how-apache-handles-requests" title="Permalink to this headline">¶</a></h2>
<p>Apache processes requests in <em class="dfn">phases</em>. For example, the first
phase may be to authenticate the user, the next phase to verify
whether that user is allowed to see a particular file, then (next
phase) read the file and send it to the client. A typical static file
request involves three phases: (1) translate the requested URI to a
file location (2) read the file and send it to the client, then (3)
log the request. Exactly which phases are processed and how varies
greatly and depends on the configuration.</p>
<p>A <em class="dfn">handler</em> is a function that processes one phase. There may be
more than one handler available to process a particular phase, in
which case they are called by Apache in sequence. For each of the
phases, there is a default Apache handler (most of which by default
perform only very basic functions or do nothing), and then there are
additional handlers provided by Apache modules, such as mod_python.</p>
<p>Mod_python provides every possible handler to Apache. Mod_python
handlers by default do not perform any function, unless specifically
told so by a configuration directive. These directives begin with
<tt class="docutils literal"><span class="pre">'Python'</span></tt> and end with <tt class="docutils literal"><span class="pre">'Handler'</span></tt>
(e.g. <tt class="docutils literal"><span class="pre">PythonAuthenHandler</span></tt>) and associate a phase with a Python
function. So the main function of mod_python is to act as a dispatcher
between Apache handlers and Python functions written by a developer
like you.</p>
<p>The most commonly used handler is <tt class="docutils literal"><span class="pre">PythonHandler</span></tt>. It handles the
phase of the request during which the actual content is
provided. Because it has no name, it is sometimes referred to as as
<em class="dfn">generic</em> handler. The default Apache action for this handler is
to read the file and send it to the client. Most applications you will
write will provide this one handler. To see all the possible
handlers, refer to Section <a class="reference internal" href="directives.html#directives"><em>Apache Configuration Directives</em></a>.</p>
</div>
<div class="section" id="so-what-exactly-does-mod-python-do">
<span id="tut-what-it-do"></span><h2>So what Exactly does Mod-python do?<a class="headerlink" href="#so-what-exactly-does-mod-python-do" title="Permalink to this headline">¶</a></h2>
<p>Let&#8217;s pretend we have the following configuration:</p>
<div class="highlight-python"><pre>&lt;Directory /mywebdir&gt;
    AddHandler mod_python .py
    PythonHandler myscript
    PythonDebug On
&lt;/Directory&gt;</pre>
</div>
<p>Note: <tt class="docutils literal"><span class="pre">/mywebdir</span></tt> is an absolute physical path in this case.</p>
<p>And let&#8217;s say that we have a python program (Windows users: substitute
forward slashes for backslashes) <tt class="file docutils literal"><span class="pre">/mywedir/myscript.py</span></tt> that looks like
this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>

<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>

    <span class="n">req</span><span class="o">.</span><span class="n">content_type</span> <span class="o">=</span> <span class="s">&quot;text/plain&quot;</span>
    <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;Hello World!&quot;</span><span class="p">)</span>

    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
<p>Here is what&#8217;s going to happen: The <tt class="docutils literal"><span class="pre">AddHandler</span></tt> directive tells
Apache that any request for any file ending with <tt class="file docutils literal"><span class="pre">.py</span></tt> in the
<tt class="file docutils literal"><span class="pre">/mywebdir</span></tt> directory or a subdirectory thereof needs to be
processed by mod_python. The <tt class="docutils literal"><span class="pre">'PythonHandler</span> <span class="pre">myscript'</span></tt> directive
tells mod_python to process the generic handler using the
<cite>myscript</cite> script. The <tt class="docutils literal"><span class="pre">'PythonDebug</span> <span class="pre">On'</span></tt> directive instructs
mod_python in case of an Python error to send error output to the
client (in addition to the logs), very useful during development.</p>
<p>When a request comes in, Apache starts stepping through its request
processing phases calling handlers in mod_python. The mod_python
handlers check whether a directive for that handler was specified in
the configuration. (Remember, it acts as a dispatcher.)  In our
example, no action will be taken by mod_python for all handlers except
for the generic handler. When we get to the generic handler,
mod_python will notice <tt class="docutils literal"><span class="pre">'PythonHandler</span> <span class="pre">myscript'</span></tt> directive and do
the following:</p>
<ul>
<li><p class="first">If not already done, prepend the directory in which the
<tt class="docutils literal"><span class="pre">PythonHandler</span></tt> directive was found to <tt class="docutils literal"><span class="pre">sys.path</span></tt>.</p>
</li>
<li><p class="first">Attempt to import a module by name <tt class="docutils literal"><span class="pre">myscript</span></tt>. (Note that if
<tt class="docutils literal"><span class="pre">myscript</span></tt> was in a subdirectory of the directory where
<tt class="docutils literal"><span class="pre">PythonHandler</span></tt> was specified, then the import would not work
because said subdirectory would not be in the <tt class="docutils literal"><span class="pre">sys.path</span></tt>. One
way around this is to use package notation, e.g.
<tt class="docutils literal"><span class="pre">'PythonHandler</span> <span class="pre">subdir.myscript'</span></tt>.)</p>
</li>
<li><p class="first">Look for a function called <tt class="docutils literal"><span class="pre">handler</span></tt> in module <tt class="docutils literal"><span class="pre">myscript</span></tt>.</p>
</li>
<li><p class="first">Call the function, passing it a request object. (More on what a
request object is later).</p>
</li>
<li><p class="first">At this point we&#8217;re inside the script, let&#8217;s examine it line-by-line:</p>
<ul>
<li><div class="first highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>
</pre></div>
</div>
<p>This imports the apache module which provides the interface to
Apache. With a few rare exceptions, every mod_python program will have
this line.</p>
</li>
</ul>
<ul id="index-0">
<li><div class="first highlight-python"><pre>def handler(req):</pre>
</div>
<p>This is our <em class="dfn">handler</em> function declaration. It
is called <tt class="docutils literal"><span class="pre">'handler'</span></tt> because mod_python takes the name of the
directive, converts it to lower case and removes the word
<tt class="docutils literal"><span class="pre">'python'</span></tt>. Thus <tt class="docutils literal"><span class="pre">'PythonHandler'</span></tt> becomes
<tt class="docutils literal"><span class="pre">'handler'</span></tt>. You could name it something else, and specify it
explicitly in the directive using <tt class="docutils literal"><span class="pre">'::'</span></tt>. For example, if the
handler function was called <tt class="docutils literal"><span class="pre">'spam'</span></tt>, then the directive would
be <tt class="docutils literal"><span class="pre">'PythonHandler</span> <span class="pre">myscript::spam'</span></tt>.</p>
<p>Note that a handler must take one argument - the <a class="reference internal" href="pythonapi.html#pyapi-mprequest"><em>Request Object</em></a>.
The request object is an object that provides all of the
information about this particular request - such as the IP of
client, the headers, the URI, etc. The communication back to the
client is also done via the request object, i.e. there is no
&#8220;response&#8221; object.</p>
</li>
<li><div class="first highlight-python"><div class="highlight"><pre><span class="n">req</span><span class="o">.</span><span class="n">content_type</span> <span class="o">=</span> <span class="s">&quot;text/plain&quot;</span>
</pre></div>
</div>
<p>This sets the content type to <tt class="docutils literal"><span class="pre">'text/plain'</span></tt>. The default is
usually <tt class="docutils literal"><span class="pre">'text/html'</span></tt>, but because our handler does not produce
any html, <tt class="docutils literal"><span class="pre">'text/plain'</span></tt> is more appropriate.  You should always
make sure this is set <em>before</em> any call to <tt class="docutils literal"><span class="pre">'req.write'</span></tt>. When
you first call <tt class="docutils literal"><span class="pre">'req.write'</span></tt>, the response HTTP header is sent
to the client and all subsequent changes to the content type (or
other HTTP headers) have no effect.</p>
</li>
<li><div class="first highlight-python"><div class="highlight"><pre><span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;Hello World!&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>This writes the <tt class="docutils literal"><span class="pre">'Hello</span> <span class="pre">World!'</span></tt> string to the client.</p>
</li>
<li><div class="first highlight-python"><div class="highlight"><pre><span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
<p>This tells Apache that everything went OK and that the request has
been processed. If things did not go OK, this line could return
<tt class="xref py py-const docutils literal"><span class="pre">apache.HTTP_INTERNAL_SERVER_ERROR</span></tt> or
<tt class="xref py py-const docutils literal"><span class="pre">apache.HTTP_FORBIDDEN</span></tt>. When things do not go OK, Apache
logs the error and generates an error message for the client.</p>
</li>
</ul>
</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is important to understand that in order for the handler code to
be executed, the URL needs not refer specficially to
<tt class="file docutils literal"><span class="pre">myscript.py</span></tt>. The only requirement is that it refers to a
<tt class="file docutils literal"><span class="pre">.py</span></tt> file. This is because the <tt class="docutils literal"><span class="pre">AddHandler</span> <span class="pre">mod_python</span> <span class="pre">.py</span></tt>
directive assignes mod_python to be a handler for a file <em>type</em>
(based on extention <tt class="docutils literal"><span class="pre">.py</span></tt>), not a specific file. Therefore the
name in the URL does not matter, in fact the file referred to in the
URL doesn&#8217;t event have to exist. Given the above configuration,
<tt class="docutils literal"><span class="pre">'http://myserver/mywebdir/myscript.py'</span></tt> and
<tt class="docutils literal"><span class="pre">'http://myserver/mywebdir/montypython.py'</span></tt> would yield the exact
same result.</p>
</div>
</div>
<div class="section" id="now-something-more-complicated-authentication">
<span id="tut-more-complicated"></span><h2>Now something More Complicated - Authentication<a class="headerlink" href="#now-something-more-complicated-authentication" title="Permalink to this headline">¶</a></h2>
<p>Now that you know how to write a basic handler, let&#8217;s try
something more complicated.</p>
<p>Let&#8217;s say we want to password-protect this directory. We want the
login to be <tt class="docutils literal"><span class="pre">'spam'</span></tt>, and the password to be <tt class="docutils literal"><span class="pre">'eggs'</span></tt>.</p>
<p>First, we need to tell Apache to call our <em>authentication</em>
handler when authentication is needed. We do this by adding the
<tt class="docutils literal"><span class="pre">PythonAuthenHandler</span></tt>. So now our config looks like this:</p>
<div class="highlight-python"><pre>&lt;Directory /mywebdir&gt;
    AddHandler mod_python .py
    PythonHandler myscript
    PythonAuthenHandler myscript
    PythonDebug On
&lt;/Directory&gt;</pre>
</div>
<p>Notice that the same script is specified for two different
handlers. This is fine, because if you remember, mod_python will look
for different functions within that script for the different handlers.</p>
<p>Next, we need to tell Apache that we are using Basic HTTP
authentication, and only valid users are allowed (this is fairly basic
Apache stuff, so we&#8217;re not going to go into details here). Our config
looks like this now:</p>
<div class="highlight-python"><pre>&lt;Directory /mywebdir&gt;
   AddHandler mod_python .py
   PythonHandler myscript
   PythonAuthenHandler myscript
   PythonDebug On
   AuthType Basic
   AuthName "Restricted Area"
   require valid-user
&lt;/Directory&gt;</pre>
</div>
<p>Note that depending on which version of Apache is being used, you may need
to set either the code{AuthAuthoritative} or <tt class="docutils literal"><span class="pre">AuthBasicAuthoritative</span></tt>
directive to <tt class="docutils literal"><span class="pre">Off</span></tt> to tell Apache that you want allow the task of
performing basic authentication to fall through to your handler.</p>
<p>Now we need to write an authentication handler function in
<tt class="file docutils literal"><span class="pre">myscript.py</span></tt>. A basic authentication handler would look like
this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>

<span class="k">def</span> <span class="nf">authenhandler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>

    <span class="n">pw</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">get_basic_auth_pw</span><span class="p">()</span>
    <span class="n">user</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">user</span>

    <span class="k">if</span> <span class="n">user</span> <span class="o">==</span> <span class="s">&quot;spam&quot;</span> <span class="ow">and</span> <span class="n">pw</span> <span class="o">==</span> <span class="s">&quot;eggs&quot;</span><span class="p">:</span>
       <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
    <span class="k">else</span><span class="p">:</span>
       <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">HTTP_UNAUTHORIZED</span>
</pre></div>
</div>
<p>Let&#8217;s look at this line by line:</p>
<ul>
<li><div class="first highlight-python"><pre>def authenhandler(req):</pre>
</div>
<p>This is the handler function declaration. This one is called
<tt class="docutils literal"><span class="pre">authenhandler</span></tt> because, as we already described above,
mod_python takes the name of the directive
(<tt class="docutils literal"><span class="pre">PythonAuthenHandler</span></tt>), drops the word <tt class="docutils literal"><span class="pre">'Python'</span></tt> and converts
it lower case.</p>
</li>
<li><div class="first highlight-python"><div class="highlight"><pre><span class="n">pw</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">get_basic_auth_pw</span><span class="p">()</span>
</pre></div>
</div>
<p>This is how we obtain the password. The basic HTTP authentication
transmits the password in base64 encoded form to make it a little
bit less obvious. This function decodes the password and returns it
as a string. Note that we have to call this function before obtaining
the user name.</p>
</li>
<li><div class="first highlight-python"><div class="highlight"><pre><span class="n">user</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">user</span>
</pre></div>
</div>
<p>This is how you obtain the username that the user entered.</p>
</li>
<li><div class="first highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">user</span> <span class="o">==</span> <span class="s">&quot;spam&quot;</span> <span class="ow">and</span> <span class="n">pw</span> <span class="o">==</span> <span class="s">&quot;eggs&quot;</span><span class="p">:</span>
    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
<p>We compare the values provided by the user, and if they are what we
were expecting, we tell Apache to go ahead and proceed by returning
<tt class="xref py py-const docutils literal"><span class="pre">apache.OK</span></tt>. Apache will then consider this phase of the
request complete, and proceed to the next phase. (Which in this case
would be <tt class="xref py py-func docutils literal"><span class="pre">handler()</span></tt> if it&#8217;s a <tt class="docutils literal"><span class="pre">'.py'</span></tt> file).</p>
</li>
<li><div class="first highlight-python"><pre>else:
    return apache.HTTP_UNAUTHORIZED</pre>
</div>
<p>Else, we tell Apache to return <tt class="xref py py-const docutils literal"><span class="pre">HTTP_UNAUTHORIZED</span></tt> to the
client, which usually causes the browser to pop a dialog box asking
for username and password.</p>
</li>
</ul>
</div>
<div class="section" id="your-own-404-handler">
<span id="tut-404-handler"></span><h2>Your Own 404 Handler<a class="headerlink" href="#your-own-404-handler" title="Permalink to this headline">¶</a></h2>
<p>In some cases, you may wish to return a 404 (<tt class="xref py py-const docutils literal"><span class="pre">HTTP_NOT_FOUND</span></tt>) or
other non-200 result from your handler.  There is a trick here.  if you
return <tt class="xref py py-const docutils literal"><span class="pre">HTTP_NOT_FOUND</span></tt> from your handler, Apache will handle
rendering an error page.  This can be problematic if you wish your handler
to render it&#8217;s own error page.</p>
<p>In this case, you need to set <tt class="docutils literal"><span class="pre">req.status</span> <span class="pre">=</span> <span class="pre">apache.HTTP_NOT_FOUND</span></tt>,
render your page, and then <tt class="docutils literal"><span class="pre">return(apache.OK)</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>

<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>
   <span class="k">if</span> <span class="n">req</span><span class="o">.</span><span class="n">filename</span><span class="p">[</span><span class="o">-</span><span class="mi">17</span><span class="p">:]</span> <span class="o">==</span> <span class="s">&#39;apache-error.html&#39;</span><span class="p">:</span>
      <span class="c">#  make Apache report an error and render the error page</span>
      <span class="k">return</span><span class="p">(</span><span class="n">apache</span><span class="o">.</span><span class="n">HTTP_NOT_FOUND</span><span class="p">)</span>
   <span class="k">if</span> <span class="n">req</span><span class="o">.</span><span class="n">filename</span><span class="p">[</span><span class="o">-</span><span class="mi">18</span><span class="p">:]</span> <span class="o">==</span> <span class="s">&#39;handler-error.html&#39;</span><span class="p">:</span>
      <span class="c">#  use our own error page</span>
      <span class="n">req</span><span class="o">.</span><span class="n">status</span> <span class="o">=</span> <span class="n">apache</span><span class="o">.</span><span class="n">HTTP_NOT_FOUND</span>
      <span class="n">pagebuffer</span> <span class="o">=</span> <span class="s">&#39;Page not here.  Page left, not know where gone.&#39;</span>
   <span class="k">else</span><span class="p">:</span>
      <span class="c">#  use the contents of a file</span>
      <span class="n">pagebuffer</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">req</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="s">&#39;r&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>

   <span class="c">#  fall through from the latter two above</span>
   <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">pagebuffer</span><span class="p">)</span>
   <span class="k">return</span><span class="p">(</span><span class="n">apache</span><span class="o">.</span><span class="n">OK</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that if wishing to returning an error page from a handler phase other
than the response handler, the value <tt class="docutils literal"><span class="pre">apache.DONE</span></tt> must be returned
instead of <tt class="docutils literal"><span class="pre">apache.OK</span></tt>. If this is not done, subsequent handler phases
will still be run. The value of <tt class="docutils literal"><span class="pre">apache.DONE</span></tt> indicates that processing
of the request should be stopped immediately. If using stacked response
handlers, then <tt class="docutils literal"><span class="pre">apache.DONE</span></tt> should also be returned in that situation
to prevent subsequent handlers registered for that phase being run if
appropriate.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Tutorial</a><ul>
<li><a class="reference internal" href="#a-quick-start-with-the-publisher-handler">A Quick Start with the Publisher Handler</a></li>
<li><a class="reference internal" href="#quick-overview-of-how-apache-handles-requests">Quick Overview of how Apache Handles Requests</a></li>
<li><a class="reference internal" href="#so-what-exactly-does-mod-python-do">So what Exactly does Mod-python do?</a></li>
<li><a class="reference internal" href="#now-something-more-complicated-authentication">Now something More Complicated - Authentication</a></li>
<li><a class="reference internal" href="#your-own-404-handler">Your Own 404 Handler</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="installation.html"
                        title="previous chapter">Installation</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="pythonapi.html"
                        title="next chapter">Python API</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/tutorial.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="pythonapi.html" title="Python API"
             >next</a> |</li>
        <li class="right" >
          <a href="installation.html" title="Installation"
             >previous</a> |</li>
        <li><a href="contents.html">Mod_python v3.5.0-3.5.0 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; <a href="copyright.html">Copyright</a> 1990-2013, Apache Software Foundation, Gregory Trubetskoy.
      Last updated on Nov 13, 2013.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
    </div>
  </body>
</html>